Node / meshtastic / Meshtastic-Android / files / feature / map / README.md

Displaying Raw • View rendered • Download

Tc9d1d9# `:feature:map`

Tc9d1d9## Overview

The Ta5d6ff`:feature:map` module provides the mapping interface for the application. Map rendering is decomposed into four focused provider contracts, each with per-flavor implementations in Ta5d6ff`:androidApp`.

Tc9d1d9## Architecture

Tc9d1d9### Provider Contracts (in `core:ui/commonMain`)

Ta5d6ff`MapViewProvider` is a named interface (exposed via Ta5d6ff`LocalMapViewProvider`); the other three are Ta5d6ff`CompositionLocal`s in Ta5d6ff`core/ui/.../util/`.

| Contract | Purpose | Implementations |

|---|---|---|

| Ta5d6ff`MapViewProvider` | Main map (nodes, waypoints, controls) | Ta5d6ff`GoogleMapViewProvider`, Ta5d6ff`FdroidMapViewProvider` |

| Ta5d6ff`LocalNodeTrackMapProvider` | Per-node GPS track overlay (embedded in Ta5d6ff`PositionLogScreens.kt`, Ta5d6ff`feature:node`) | Google: Ta5d6ff`NodeTrackMap` → Ta5d6ff`MapView(GoogleMapMode.NodeTrack)`, F-Droid: Ta5d6ff`NodeTrackMap` → Ta5d6ff`NodeTrackOsmMap` |

| Ta5d6ff`LocalTracerouteMapProvider` | Traceroute route visualization | Google: Ta5d6ff`TracerouteMap` → Ta5d6ff`MapView(GoogleMapMode.Traceroute)`, F-Droid: Ta5d6ff`TracerouteMap` → Ta5d6ff`TracerouteOsmMap` |

| Ta5d6ff`LocalDiscoveryMapProvider` | Embedded discovery-scan map (node markers + topology polylines, Ta5d6ff`feature:discovery`) | Google: Ta5d6ff`DiscoveryMap` → Ta5d6ff`DiscoveryGoogleMap`, F-Droid: Ta5d6ff`DiscoveryMap` → Ta5d6ff`DiscoveryOsmMap` |

All providers are injected via Ta5d6ff`CompositionLocal` in Ta5d6ff`MainActivity.kt` and consumed by feature modules without direct dependency on Google Maps or osmdroid.

Tc9d1d9### Shared ViewModels (in `commonMain`)

Tff7b72- **`BaseMapViewModel`** — Core contract for all map state management, node markers, camera positions, and traceroute node selection logic (Ta5d6ff`TracerouteNodeSelection`, Ta5d6ff`tracerouteNodeSelection()`).

Tff7b72- **`NodeMapViewModel`** — Shared logic for per-node map views (track display, position history).

Tc9d1d9### Key Data Types

Tff7b72- **`TracerouteOverlay`** (Ta5d6ff`core:model/commonMain`) — Pure data class representing traceroute route segments. Extracted from Ta5d6ff`feature:map` for cross-module reuse.

Tff7b72- **`TracerouteNodeSelection`** (Ta5d6ff`feature:map/commonMain`) — Data class modeling node selection results during traceroute visualization.

Tff7b72- **`GeoConstants`** (Ta5d6ff`core:model/commonMain`) — Centralized geographic constants (Ta5d6ff`DEG_D`, Ta5d6ff`HEADING_DEG`, Ta5d6ff`EARTH_RADIUS_METERS`).

Tc9d1d9## Map Providers

Tff7b72- **Google Maps (`google` flavor)**: Uses Google Play Services Maps SDK. Implementations in Ta5d6ff`androidApp/src/google/kotlin/org/meshtastic/app/map/`.

Tff7b72- **OpenStreetMap (`fdroid` flavor)**: Uses Ta5d6ff`osmdroid` for a fully open-source experience. Implementations in Ta5d6ff`androidApp/src/fdroid/kotlin/org/meshtastic/app/map/`.

Tc9d1d9## Features

Tff7b72- **Live Node Tracking**: Real-time position updates for nodes on the mesh.

Tff7b72- **Waypoints**: Create and share points of interest.

Tff7b72- **Per-Node Track Overlay**: Embedded map in Ta5d6ff`PositionLogScreens.kt` (Ta5d6ff`feature:node`) showing a node's GPS track history.

Tff7b72- **Traceroute Visualization**: Dedicated map view showing route segments between mesh nodes.

Tff7b72- **Offline Maps**: Support for pre-downloaded map tiles (via Ta5d6ff`osmdroid`).

Tc9d1d9## Dependency Graph

<!--region graph-->

Ta5d6ff```Ta5d6ffmermaid

Ta5d6ffgraph TB

:feature:map[map]:::kmp-feature

:feature:map -.-> :core:data

:feature:map -.-> :core:database

:feature:map -.-> :core:datastore

:feature:map -.-> :core:model

:feature:map -.-> :core:navigation

:feature:map -.-> :core:prefs

:feature:map -.-> :core:service

:feature:map -.-> :core:resources

:feature:map -.-> :core:ui

:feature:map -.-> :core:di

:feature:map -.-> :core:testing

classDef android-application fill:#CAFFBF,stroke:#000,stroke-width:2px,color:#000;

classDef android-application-compose fill:#CAFFBF,stroke:#000,stroke-width:2px,color:#000;

classDef compose-desktop-application fill:#CAFFBF,stroke:#000,stroke-width:2px,color:#000;

classDef android-feature fill:#FFD6A5,stroke:#000,stroke-width:2px,color:#000;

classDef android-library fill:#9BF6FF,stroke:#000,stroke-width:2px,color:#000;

classDef android-library-compose fill:#9BF6FF,stroke:#000,stroke-width:2px,color:#000;

classDef android-test fill:#A0C4FF,stroke:#000,stroke-width:2px,color:#000;

classDef jvm-library fill:#BDB2FF,stroke:#000,stroke-width:2px,color:#000;

classDef kmp-feature fill:#FFD6A5,stroke:#000,stroke-width:2px,color:#000;

classDef kmp-library-compose fill:#FFC1CC,stroke:#000,stroke-width:2px,color:#000;

classDef kmp-library fill:#FFC1CC,stroke:#000,stroke-width:2px,color:#000;

classDef unknown fill:#FFADAD,stroke:#000,stroke-width:2px,color:#000;

Ta5d6ff```

<!--endregion-->